05.04.2025

Better Callouts Documentation - v0.0.1

Version: 0.0.1 (Pre-release)
This version may be unstable!

Info

Better Callouts is an Obsidian plugin that lets you create, edit, and manage custom callout styles visually — no CSS[1] knowledge needed. It handles everything for you, including automatic snippet generation.

Features

  • Visual editor for creating custom callouts
  • Custom color, text color, and optional border for the callouts (no icons)
  • Automatically generates Obsidian CSS snippets
  • Automatically keeps .obsidian/snippets/betterCallouts.css up to date
  • Easy inserting the custom callouts into your notes

Getting started

1. Enabling the Plugin

  • Go to the plugin folder of your vault: .obsidian/plugins/ (if it doesnt exist yet create the folder)
  • create a folder called better-callouts
  • Go to 
    https://github.com/hannesschacherl/better-callouts/releases/tag/0.0.1
  • Grab the main.js and the manifest.json file and save them to your folder.
  • Enable the plugin in Settings → Community Plugins
  • Add a new Callout (this makes the plugin add everything to the CSS-File)
  • Go to Settings → Appearance Scroll down to CSS-Snippets
  • Enable BetterCallouts (This applies all styles created by the plugin to your notes)

If you use Obsidian Publish[2]:

  • Add the changes from the .obsidian/snippets/betterCallouts.css to your publish.css file for them to work on the published Obsidian
  • I recommend setting up a file watcher that watches the .obsidian/snippets/ folder and runs a shell script to merge the files into your publish.css when detecting changes

2. Plugin Settings & Creation

Settings Page

You can reach the plugins settings page by going to the Community plugins list in the Settings and opening Better Callouts.

Alternatively you can open the command palette with CTRL/CMD + P and searching for Better Callouts: Manage Callouts.

The settings page should look like this:

Creating a Callout

  • Go to Settings → Better Callouts
  • Click the + button to add a new callout
  • A callout with the name c-new appears
  • Fill out the following fields:
    • Label: Name of the callout (e.g. "Warning") [3]
    • Color: Background color
    • Text: Text color
    • Border: (optional) Add a left border
    • Border Color: (only if Border is set to yes) Add a color for the border
  • The callout preview will update in real time.
  • Your callout will be saved automatically and added to the generated CSS snippet.

Accepted Colors

The colors accepted by the plugin are:

  • Named colors (e.g. red, blue, darkgreen)
  • HEX values (e.g. #ffcc00, #123456)
  • RGB and RGBA (e.g. rgb(255, 0, 0), rgba(0, 128, 255, 0.2))
  • HSL and HSLA (e.g. hsl(200, 100%, 50%), hsla(0, 100%, 50%, 0.5))
  • Obsidian variables (e.g. var(--text-accent), var(--color-base-40))

If you're curious about the accepted colors:

To help you get started the plugin adds 3 default callouts with color values applied:

  • c-clean uses Obsidians color-variables
  • c-primary uses an RGBA color, sets Text to black (#000000) and has a border
  • c-accent uses an HSL color and sets Text to Darkgray (#222222)

When creating a callout please check the design for both dark and light mode. If Obsidians font color is hard to read in either mode you may need to set it to a specific color value like #000000 instead of using Obsidians var(--text-normal).

The advantage of using Obsidians var(--text-normal) is that this changes color depending on light- & dark-mode. In light mode the text has a dark, in dark mode a light color.

The same advantage also applies to possible background colors like var(--color-base-30). Using Obsidian color variables may help you design callouts that better fit in with the rest of the page.

Warning

if you use something like var(--some-var) and forget the closing ) other callouts may stop working.
Input validation is planned for the future but currently not active. For now just make sure your input is like the colors accepted and every ( that is opened needs to be closed.

Technical note

The plugin uses CSS variables like:

  • --callout-bg,
  • --callout-title-color,
  • and --callout-border

to apply styles.
If you're using custom CSS Styles make sure these variables and the CSS Styles for callouts are not modified or they may interfere with the plugins functionality.

Reordering Callouts

You can reorder your callouts by simply dragging and dropping them in the settings view.
This affects the order in which they appear in the modal for inserting and also how they're saved in the CSS-File.

Just click and drag the callout title area to a new position.

3. Inserting templates

You can insert your custom callouts into your file using markdown code like this: 

> [!c-my-callout] Title
> Content

The Title ([!c-my-callout]) for the callout you want to add is displayed in the settings screen of this plugin.

Inserting via modal

If you want an even easier way for inserting the callouts you can:

  • press CTRL/CMD + P (to open the command palette)
  • search for Better Callouts: Insert better callout (only works when in edit mode)
  • select the callout you want to insert from the modal

This adds the callout with basic Text to to your file and can then be edited by you. The inserted callout will also look like this:
Edit mode 

> [!c-my-callout] Title
> Contents

View mode

Title

Contents

Where is everything located?

The Plugin uses the following files:

Vault
├── .obsidian
│   ├── plugins
│   │   ├── better-callouts
│   │   │   ├── data.json
│   │   │   ├── main.js
│   │   │   └── manifest.json
│   ├── snippets
│   │   ├── betterCallouts.css

Base plugin files:
plugins > better-callouts > main.js: here is the logic for everything this plugin does

plugins > better-callouts > manifest.json: tells obsidian information about this plugin

Autogenerated plugin files:
plugins > better-callouts > data.json: here are all your custom callouts stored

snippets > betterCallouts.css: this is the automatically generated CSS-File



Footnotes

  1. CSS is what makes websites look nice by adding colors, spacing, and styles to the content you see.↩︎

  2. https://obsidian.md/publish↩︎

  3. Giving two callouts the same name will result in them overwriting each others styles↩︎